User defined functions

User defined functions can be created by putting a sequence of @commands within a procedure and then calling it as a named function.

Functions are identified by the use of word FUNCTION at the top of the procedure, followed by the parameters being passed to and from the function.

Syntax: FUNCTION (paramName: paramType [, paramName: paramType] ) [: returnType]

The FUNCTION statement would then be followed by the required sequence of @commands and terminated by use of the @Return command. Note that the return value must be of the same type that is specified by the function returnType parameter.

To be recognised as a function, the word FUNCTION must be used as the first text of the first line of the procedure.

The paramType can be either 'S' for a string or 'N' for a number.

The S or N parameter can be preceded with an * which would then pass the values to the function by reference. When a parameter is passed by reference, any changes made to the variable in the function will be reflected in the value of the calling procedure. If the * is omitted, variables are passed by value, where any changes made in the function would not be reflected in the calling procedure.

The @Dim command can be very useful in functions to define local variables for temporary use within a procedure.

Examples:

In a command procedure called 'GetLocation':

FUNCTION ( name : s ) : S
@SelectCase name 
  @Case 'John'
    @Return 'Manchester'
  @Case 'Fred'
    @Return 'London'
  @Case 'Bob'
    @Return 'Edinburgh'
@EndSelect

The above function could be called from a command such as:

@Debug GetLocation ('John')

where the value 'Manchester' would be returned and displayed in the debug dialog box.

In a command procedure called 'ErrorRep':

FUNCTION ( errorNo : n )
@SelectCase errorNo 
  @Case 1
    @Debug 'The file could not be found'
  @Case 2
    @Debug 'An error occurred during writing'
  @Case 3
     @Debug 'An error occurred during reading'
@EndSelect

This function could be called by:

@Do ErrorRep (1)

Using embedded functions

You can also call functions by embedding them within text boxes, such as in label controls on Dialogs or within Reports. For example, you could put this line of text in a report:

John's location is {GetLocation ('John')}

which would invoke the GetLocation function when the report is called.

Within functions, you may also find it very useful to make Indirect references to variables.